home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / g_man / cat3 / OpenGL / glcopypixels.z / glcopypixels
Encoding:
Text File  |  2001-04-17  |  23.1 KB  |  344 lines
  1.  
  2.  
  3.  
  4. ggggllllCCCCooooppppyyyyPPPPiiiixxxxeeeellllssss((((3333GGGG))))               OOOOppppeeeennnnGGGGLLLL RRRReeeeffffeeeerrrreeeennnncccceeee               ggggllllCCCCooooppppyyyyPPPPiiiixxxxeeeellllssss((((3333GGGG))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      ggggllllCCCCooooppppyyyyPPPPiiiixxxxeeeellllssss - copy pixels in the frame buffer
  10.  
  11.  
  12. CCCC SSSSPPPPEEEECCCCIIIIFFFFIIIICCCCAAAATTTTIIIIOOOONNNN
  13.      void ggggllllCCCCooooppppyyyyPPPPiiiixxxxeeeellllssss( GLint _x,
  14.                         GLint _y,
  15.                         GLsizei _w_i_d_t_h,
  16.                         GLsizei _h_e_i_g_h_t,
  17.                         GLenum _t_y_p_e )
  18.  
  19.  
  20. PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRRSSSS
  21.      _x, _y Specify the window coordinates of the lower left corner of the
  22.           rectangular region of pixels to be copied.
  23.  
  24.      _w_i_d_t_h, _h_e_i_g_h_t
  25.           Specify the dimensions of the rectangular region of pixels to be
  26.           copied.  Both must be nonnegative.
  27.  
  28.      _t_y_p_e Specifies whether color values, depth values, or stencil values are
  29.           to be copied.  Symbolic constants GGGGLLLL____CCCCOOOOLLLLOOOORRRR, GGGGLLLL____DDDDEEEEPPPPTTTTHHHH, and GGGGLLLL____SSSSTTTTEEEENNNNCCCCIIIILLLL
  30.           are accepted.
  31.  
  32. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  33.      ggggllllCCCCooooppppyyyyPPPPiiiixxxxeeeellllssss copies a screen-aligned rectangle of pixels from the
  34.      specified frame buffer location to a region relative to the current
  35.      raster position.  Its operation is well defined only if the entire pixel
  36.      source region is within the exposed portion of the read window associated
  37.      with the current context.  Results of copies from outside the window, or
  38.      from regions of the window that are not exposed, are hardware dependent
  39.      and undefined.
  40.  
  41.      _x and _y specify the window coordinates of the lower left corner of the
  42.      rectangular region to be copied.  _w_i_d_t_h and _h_e_i_g_h_t specify the dimensions
  43.      of the rectangular region to be copied.  Both _w_i_d_t_h and _h_e_i_g_h_t must not
  44.      be negative.
  45.  
  46.      Several parameters control the processing of the pixel data while it is
  47.      being copied.  These parameters are set with three commands:
  48.      ggggllllPPPPiiiixxxxeeeellllTTTTrrrraaaannnnssssffffeeeerrrr, ggggllllPPPPiiiixxxxeeeellllMMMMaaaapppp, and ggggllllPPPPiiiixxxxeeeellllZZZZoooooooommmm.  The state of
  49.      GGGGLLLL____IIIINNNNTTTTEEEERRRRLLLLAAAACCCCEEEE____SSSSGGGGIIIIXXXX and GGGGLLLL____IIIINNNNTTTTEEEERRRRLLLLAAAACCCCEEEE____RRRREEEEAAAADDDD____IIIINNNNGGGGRRRR, controlled by ggggllllEEEEnnnnaaaabbbblllleeee and
  50.      ggggllllDDDDiiiissssaaaabbbblllleeee, also affect the result of ggggllllCCCCooooppppyyyyPPPPiiiixxxxeeeellllssss.  This reference page
  51.      describes the effects on ggggllllCCCCooooppppyyyyPPPPiiiixxxxeeeellllssss of most, but not all, of these
  52.      parameters.  In addition the convolution, histogram, and minmax
  53.      operations may affect the result of ggggllllCCCCooooppppyyyyPPPPiiiixxxxeeeellllssss.  See the reference
  54.      pages for ggggllllCCCCoooonnnnvvvvoooolllluuuuttttiiiioooonnnnFFFFiiiilllltttteeeerrrr2222DDDDEEEEXXXXTTTT, ggggllllHHHHiiiissssttttooooggggrrrraaaammmmEEEEXXXXTTTT, and ggggllllMMMMiiiinnnnmmmmaaaaxxxxEEEEXXXXTTTT for
  55.      more information.
  56.  
  57.      ggggllllCCCCooooppppyyyyPPPPiiiixxxxeeeellllssss copies values from each pixel with the lower left-hand
  58.      corner at (_x + i, _y + j) for 0 _< i < _w_i_d_t_h and 0 _< j < _h_e_i_g_h_t.  This
  59.      pixel is said to be the ith pixel in the jth row. Pixels are copied in
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. ggggllllCCCCooooppppyyyyPPPPiiiixxxxeeeellllssss((((3333GGGG))))               OOOOppppeeeennnnGGGGLLLL RRRReeeeffffeeeerrrreeeennnncccceeee               ggggllllCCCCooooppppyyyyPPPPiiiixxxxeeeellllssss((((3333GGGG))))
  71.  
  72.  
  73.  
  74.      row order from the lowest to the highest row, left to right in each row.
  75.  
  76.      _t_y_p_e specifies whether color, depth, or stencil data is to be copied.
  77.      The details of the transfer for each data type are as follows:
  78.  
  79.      GGGGLLLL____CCCCOOOOLLLLOOOORRRR       Indices or RGBA colors are read from the buffer currently
  80.                     specified as the read source buffer (see ggggllllRRRReeeeaaaaddddBBBBuuuuffffffffeeeerrrr).
  81.                     If the GL is in color index mode, each index that is read
  82.                     from this buffer is converted to a fixed-point format with
  83.                     an unspecified number of bits to the right of the binary
  84.                     point.  Each index is then shifted left by GGGGLLLL____IIIINNNNDDDDEEEEXXXX____SSSSHHHHIIIIFFFFTTTT
  85.                     bits, and added to GGGGLLLL____IIIINNNNDDDDEEEEXXXX____OOOOFFFFFFFFSSSSEEEETTTT.  If GGGGLLLL____IIIINNNNDDDDEEEEXXXX____SSSSHHHHIIIIFFFFTTTT is
  86.                     negative, the shift is to the right.  In either case, zero
  87.                     bits fill otherwise unspecified bit locations in the
  88.                     result.  If GGGGLLLL____MMMMAAAAPPPP____CCCCOOOOLLLLOOOORRRR is true, the index is replaced
  89.                     with the value that it references in lookup table
  90.                     GGGGLLLL____PPPPIIIIXXXXEEEELLLL____MMMMAAAAPPPP____IIII____TTTTOOOO____IIII.  Whether the lookup replacement of
  91.                     the index is done or not, the integer part of the index is
  92.                                      b
  93.                     then ANDed with 2 -1, where b is the number of bits in a
  94.                     color index buffer.
  95.  
  96.                     If the GL is in RGBA mode, the red, green, blue, and alpha
  97.                     components of each pixel that is read are converted to an
  98.                     internal floating-point format with unspecified precision.
  99.                     The conversion maps the largest representable component
  100.                     value to 1.0, and component value 0 to 0.0.  The resulting
  101.                     floating-point color values are then multiplied by
  102.                     GGGGLLLL____cccc____SSSSCCCCAAAALLLLEEEE and added to GGGGLLLL____cccc____BBBBIIIIAAAASSSS, where _c is RED, GREEN,
  103.                     BLUE, and ALPHA for the respective color components.  The
  104.                     results are clamped to the range [0,1].  If GGGGLLLL____MMMMAAAAPPPP____CCCCOOOOLLLLOOOORRRR
  105.                     is true, each color component is scaled by the size of
  106.                     lookup table GGGGLLLL____PPPPIIIIXXXXEEEELLLL____MMMMAAAAPPPP____cccc____TTTTOOOO____cccc, then replaced by the
  107.                     value that it references in that table.  _c is R, G, B, or
  108.                     A.
  109.  
  110.                     If the GGGGLLLL____AAAARRRRBBBB____iiiimmmmaaaaggggiiiinnnngggg extension is supported, the color
  111.                     values may be additionally processed by color-table
  112.                     lookups, color-matrix transformations, and convolution
  113.                     filters.
  114.  
  115.                     The GL then converts the resulting indices or RGBA colors
  116.                     to fragments by attaching the current raster position _z
  117.                     coordinate and texture coordinates to each pixel, then
  118.                     assigning window coordinates (x  + i,y  + j), where
  119.                                                    r      r
  120.                     (x ,y ) is the current raster position, and the pixel was
  121.                       r  r
  122.                     the ith pixel in the jth row.  These pixel fragments are
  123.                     then treated just like the fragments generated by
  124.                     rasterizing points, lines, or polygons.  Texture mapping,
  125.                     fog, and all the fragment operations are applied before
  126.                     the fragments are written to the frame buffer.
  127.  
  128.  
  129.  
  130.  
  131.  
  132.                                                                         PPPPaaaaggggeeee 2222
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139. ggggllllCCCCooooppppyyyyPPPPiiiixxxxeeeellllssss((((3333GGGG))))               OOOOppppeeeennnnGGGGLLLL RRRReeeeffffeeeerrrreeeennnncccceeee               ggggllllCCCCooooppppyyyyPPPPiiiixxxxeeeellllssss((((3333GGGG))))
  140.  
  141.  
  142.  
  143.      GGGGLLLL____DDDDEEEEPPPPTTTTHHHH       Depth values are read from the depth buffer and converted
  144.                     directly to an internal floating-point format with
  145.                     unspecified precision.  The resulting floating-point depth
  146.                     value is then multiplied by GGGGLLLL____DDDDEEEEPPPPTTTTHHHH____SSSSCCCCAAAALLLLEEEE and added to
  147.                     GGGGLLLL____DDDDEEEEPPPPTTTTHHHH____BBBBIIIIAAAASSSS.  The result is clamped to the range [0,1].
  148.  
  149.                     The GL then converts the resulting depth components to
  150.                     fragments by attaching the current raster position color
  151.                     or color index and texture coordinates to each pixel, then
  152.                     assigning window coordinates (x  + i,y  + j), where
  153.                                                    r      r
  154.                     (x ,y ) is the current raster position, and the pixel was
  155.                       r  r
  156.                     the ith pixel in the jth row.  These pixel fragments are
  157.                     then treated just like the fragments generated by
  158.                     rasterizing points, lines, or polygons.  Texture mapping,
  159.                     fog, and all the fragment operations are applied before
  160.                     the fragments are written to the frame buffer.
  161.  
  162.      GGGGLLLL____SSSSTTTTEEEENNNNCCCCIIIILLLL     Stencil indices are read from the stencil buffer and
  163.                     converted to an internal fixed-point format with an
  164.                     unspecified number of bits to the right of the binary
  165.                     point.  Each fixed-point index is then shifted left by
  166.                     GGGGLLLL____IIIINNNNDDDDEEEEXXXX____SSSSHHHHIIIIFFFFTTTT bits, and added to GGGGLLLL____IIIINNNNDDDDEEEEXXXX____OOOOFFFFFFFFSSSSEEEETTTT.  If
  167.                     GGGGLLLL____IIIINNNNDDDDEEEEXXXX____SSSSHHHHIIIIFFFFTTTT is negative, the shift is to the right.  In
  168.                     either case, zero bits fill otherwise unspecified bit
  169.                     locations in the result.  If GGGGLLLL____MMMMAAAAPPPP____SSSSTTTTEEEENNNNCCCCIIIILLLL is true, the
  170.                     index is replaced with the value that it references in
  171.                     lookup table GGGGLLLL____PPPPIIIIXXXXEEEELLLL____MMMMAAAAPPPP____SSSS____TTTTOOOO____SSSS.  Whether the lookup
  172.                     replacement of the index is done or not, the integer part
  173.                                                      b
  174.                     of the index is then ANDed with 2 -1, where b is the
  175.                     number of bits in the stencil buffer.  The resulting
  176.                     stencil indices are then written to the stencil buffer
  177.                     such that the index read from the ith location of the jth
  178.                     row is written to location (x  + i,y  + j), where (x ,y )
  179.                                                  r      r               r  r
  180.                     is the current raster position.  Only the pixel ownership
  181.                     test, the scissor test, and the stencil writemask affect
  182.                     these write operations.
  183.  
  184.      The rasterization described thus far assumes pixel zoom factors of 1.0.
  185.      If
  186.      ggggllllPPPPiiiixxxxeeeellllZZZZoooooooommmm is used to change the x and y pixel zoom factors, pixels are
  187.      converted to fragments as follows.  If (x , y ) is the current raster
  188.                                               r   r
  189.      position, and a given pixel is in the ith location in the jth row of the
  190.      source pixel rectangle, then fragments are generated for pixels whose
  191.      centers are in the rectangle with corners at
  192.  
  193.                             (x  + zoom i, y  + zoom j)
  194.                               r       x    r       y
  195.  
  196.                                         and
  197.  
  198.                       (x  + zoom (i + 1), y  + zoom (j + 1))
  199.                         r       x          r       y
  200.  
  201.  
  202.  
  203.  
  204.  
  205.  
  206.                                                                         PPPPaaaaggggeeee 3333
  207.  
  208.  
  209.  
  210.  
  211.  
  212.  
  213. ggggllllCCCCooooppppyyyyPPPPiiiixxxxeeeellllssss((((3333GGGG))))               OOOOppppeeeennnnGGGGLLLL RRRReeeeffffeeeerrrreeeennnncccceeee               ggggllllCCCCooooppppyyyyPPPPiiiixxxxeeeellllssss((((3333GGGG))))
  214.  
  215.  
  216.  
  217.      where zoom  is the value of GGGGLLLL____ZZZZOOOOOOOOMMMM____XXXX and zoom  is the value of
  218.                x                                   y
  219.      GGGGLLLL____ZZZZOOOOOOOOMMMM____YYYY.
  220.  
  221.      When GGGGLLLL____IIIINNNNTTTTEEEERRRRLLLLAAAACCCCEEEE____RRRREEEEAAAADDDD____IIIINNNNGGGGRRRR is enabled, every other row of the source
  222.      pixel rectangle is read.  The height of the source pixel rectangle is
  223.      equivalent to 2xheight.  Only rows (y+0,y+2,...) are read and affected by
  224.      pixel transfer and copy operations.
  225.  
  226.      When GGGGLLLL____IIIINNNNTTTTEEEERRRRLLLLAAAACCCCEEEE____SSSSGGGGIIIIXXXX is enabled, every other row of the destination
  227.      pixel rectangle is modified.  The height of the destination pixel
  228.      rectangle is equivalent to 2xGGGGLLLL____ZZZZOOOOOOOOMMMM____YYYYxheight.  Only rows (y +0,y +2,...)
  229.                                                                  r    r
  230.      of the destination are modified by the copy.
  231.  
  232. EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS
  233.      To copy the color pixel in the lower left corner of the window to the
  234.      current raster position, use
  235.  
  236.           glCopyPixels(0, 0, 1, 1, GGGGLLLL____CCCCOOOOLLLLOOOORRRR);
  237.  
  238. NNNNOOOOTTTTEEEESSSS
  239.      Modes specified by ggggllllPPPPiiiixxxxeeeellllSSSSttttoooorrrreeee have no effect on the operation of
  240.      ggggllllCCCCooooppppyyyyPPPPiiiixxxxeeeellllssss.
  241.  
  242. EEEERRRRRRRROOOORRRRSSSS
  243.      GGGGLLLL____IIIINNNNVVVVAAAALLLLIIIIDDDD____EEEENNNNUUUUMMMM is generated if _t_y_p_e is not an accepted value.
  244.  
  245.      GGGGLLLL____IIIINNNNVVVVAAAALLLLIIIIDDDD____VVVVAAAALLLLUUUUEEEE is generated if either _w_i_d_t_h or _h_e_i_g_h_t is negative.
  246.  
  247.      GGGGLLLL____IIIINNNNVVVVAAAALLLLIIIIDDDD____OOOOPPPPEEEERRRRAAAATTTTIIIIOOOONNNN is generated if _t_y_p_e is GGGGLLLL____DDDDEEEEPPPPTTTTHHHH and there is no
  248.      depth buffer.
  249.  
  250.      GGGGLLLL____IIIINNNNVVVVAAAALLLLIIIIDDDD____OOOOPPPPEEEERRRRAAAATTTTIIIIOOOONNNN is generated if _t_y_p_e is GGGGLLLL____SSSSTTTTEEEENNNNCCCCIIIILLLL and there is no
  251.      stencil buffer.
  252.  
  253.      GGGGLLLL____IIIINNNNVVVVAAAALLLLIIIIDDDD____OOOOPPPPEEEERRRRAAAATTTTIIIIOOOONNNN is generated if ggggllllCCCCooooppppyyyyPPPPiiiixxxxeeeellllssss is executed between the
  254.      execution of ggggllllBBBBeeeeggggiiiinnnn and the corresponding execution of ggggllllEEEEnnnndddd.
  255.  
  256. AAAASSSSSSSSOOOOCCCCIIIIAAAATTTTEEEEDDDD GGGGEEEETTTTSSSS
  257.      ggggllllGGGGeeeetttt with argument GGGGLLLL____CCCCUUUURRRRRRRREEEENNNNTTTT____RRRRAAAASSSSTTTTEEEERRRR____PPPPOOOOSSSSIIIITTTTIIIIOOOONNNN
  258.      ggggllllGGGGeeeetttt with argument GGGGLLLL____CCCCUUUURRRRRRRREEEENNNNTTTT____RRRRAAAASSSSTTTTEEEERRRR____PPPPOOOOSSSSIIIITTTTIIIIOOOONNNN____VVVVAAAALLLLIIIIDDDD
  259.  
  260.  
  261. MMMMAAAACCCCHHHHIIIINNNNEEEE DDDDEEEEPPPPEEEENNNNDDDDEEEENNNNCCCCIIIIEEEESSSS
  262.      On RRRReeeeaaaalllliiiittttyyyyEEEEnnnnggggiiiinnnneeee, RRRReeeeaaaalllliiiittttyyyyEEEEnnnnggggiiiinnnneeee2222, and VVVVTTTTXXXX systems convolution may not be
  263.      used in the following circumstances:
  264.  
  265.           1.  When rendering to pixmaps.
  266.  
  267.           2.  When fragment processing (texturing, depth buffering, alpha
  268.               testing, multisampling, fog) is enabled.
  269.  
  270.  
  271.  
  272.  
  273.  
  274.                                                                         PPPPaaaaggggeeee 4444
  275.  
  276.  
  277.  
  278.  
  279.  
  280.  
  281. ggggllllCCCCooooppppyyyyPPPPiiiixxxxeeeellllssss((((3333GGGG))))               OOOOppppeeeennnnGGGGLLLL RRRReeeeffffeeeerrrreeeennnncccceeee               ggggllllCCCCooooppppyyyyPPPPiiiixxxxeeeellllssss((((3333GGGG))))
  282.  
  283.  
  284.  
  285.           3.  When histogramming or minmax is enabled.
  286.  
  287.           4.  When either of the pixel zoom factors has a value other than 1.0
  288.               or -1.0.
  289.  
  290.      In these cases, ggggllllDDDDrrrraaaawwwwPPPPiiiixxxxeeeellllssss and ggggllllCCCCooooppppyyyyPPPPiiiixxxxeeeellllssss report a
  291.      GGGGLLLL____IIIINNNNVVVVAAAALLLLIIIIDDDD____OOOOPPPPEEEERRRRAAAATTTTIIIIOOOONNNN error and do not transfer any pixels.
  292.  
  293.      RRRReeeeaaaalllliiiittttyyyyEEEEnnnnggggiiiinnnneeee, RRRReeeeaaaalllliiiittttyyyyEEEEnnnnggggiiiinnnneeee2222, and VVVVTTTTXXXX systems cannot copy pixels from a
  294.      video source (see ggggllllXXXXCCCCrrrreeeeaaaatttteeeeGGGGLLLLXXXXVVVViiiiddddeeeeooooSSSSoooouuuurrrrcccceeeeSSSSGGGGIIIIXXXX) when RGBA scale and bias
  295.      are not 1 and 0, respectively, or when any of texturing, alpha or depth
  296.      testing, pixel mapping, multisampling, convolution, histogram, or minmax
  297.      is enabled.  A GGGGLLLL____IIIINNNNVVVVAAAALLLLIIIIDDDD____OOOOPPPPEEEERRRRAAAATTTTIIIIOOOONNNN error will result if any of these
  298.      conditions is true when ggggllllCCCCooooppppyyyyPPPPiiiixxxxeeeellllssss is executed.
  299.  
  300.      The SSSSGGGGIIIIXXXX____iiiinnnntttteeeerrrrllllaaaacccceeee extension is supported only on IIIInnnnffffiiiinnnniiiitttteeeeRRRReeeeaaaalllliiiittttyyyy
  301.      systems, on RRRReeeeaaaalllliiiittttyyyyEEEEnnnnggggiiiinnnneeee, RRRReeeeaaaalllliiiittttyyyyEEEEnnnnggggiiiinnnneeee2222, and VVVVTTTTXXXX systems, on OOOOccccttttaaaannnneeee2222
  302.      VVVVPPPPrrrroooo systems, and on OOOO2222 systems.
  303.  
  304.      The IIIINNNNGGGGRRRR____iiiinnnntttteeeerrrrllllaaaacccceeee____rrrreeeeaaaadddd extension is supported only on OOOOccccttttaaaannnneeee2222 VVVVPPPPrrrroooo
  305.      systems, and on OOOO2222 systems.
  306.  
  307.  
  308. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  309.      ggggllllCCCCoooolllloooorrrrTTTTaaaabbbblllleeee, ggggllllCCCCoooonnnnvvvvoooolllluuuuttttiiiioooonnnnFFFFiiiilllltttteeeerrrr1111DDDD, ggggllllCCCCoooonnnnvvvvoooolllluuuuttttiiiioooonnnnFFFFiiiilllltttteeeerrrr2222DDDD, ggggllllDDDDeeeepppptttthhhhFFFFuuuunnnncccc,
  310.      ggggllllDDDDrrrraaaawwwwBBBBuuuuffffffffeeeerrrr, ggggllllDDDDrrrraaaawwwwPPPPiiiixxxxeeeellllssss, ggggllllMMMMaaaattttrrrriiiixxxxMMMMooooddddeeee, ggggllllPPPPiiiixxxxeeeellllMMMMaaaapppp, ggggllllPPPPiiiixxxxeeeellllTTTTrrrraaaannnnssssffffeeeerrrr,
  311.      ggggllllPPPPiiiixxxxeeeellllZZZZoooooooommmm, ggggllllRRRRaaaasssstttteeeerrrrPPPPoooossss, ggggllllRRRReeeeaaaaddddBBBBuuuuffffffffeeeerrrr, ggggllllRRRReeeeaaaaddddPPPPiiiixxxxeeeellllssss,
  312.      ggggllllSSSSeeeeppppaaaarrrraaaabbbblllleeeeFFFFiiiilllltttteeeerrrr2222DDDD, ggggllllSSSStttteeeennnncccciiiillllFFFFuuuunnnncccc
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.  
  338.  
  339.  
  340.                                                                         PPPPaaaaggggeeee 5555
  341.  
  342.  
  343.  
  344.